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Smalltalk as an Internet server 


I n the june issue, we demonstrated how to turn arbi¬ 
trary Text objects into HTM L, and in September 1995, 
we demonstrated how to modify VisualWorks under 
ENVY so you could store all your commentary in styled 
text. The only thing missing to have live web access to 
your Smalltalk project documentation is a server! 

We've never been fond of specific solutions to general 
problems. It would be easy to hard-code a server that is 
dedicated to serving HTML versions of Smalltalk docu¬ 
mentation, but there is so much code that is common to 
any server that we couldn't ignore the potential reuse. 

For example, a server of any kind has these needs: 

• M anage a socket name space — you can't si mply 
pick any number for your socket. 

• I n iti al i ze a socket and prepare it for use. 

• Loop forever, waitingfor connection requests 
• Record service requests in a log. 

• Screen service requests for security reasons 
• Fork off individual service requests so the main 
loop isn't unduly delayed from its primary task of 
waiting for connections. 

• Manage unexpected problemsthat might occur in 
a service request. 

• Perform the requested service: and return a result. 
The following TCP server framework for VisualWorks 
hides all but the last step, allowing the server author to 
concentrate on the actual service being provided, with¬ 
out bei ng di stracted by the mechan ics of managi ng sock¬ 
ets, processes, logs, and exceptions. 

SETTING UP A SERVER INSTANCE 

Our server is defined as: 

Object subclass: #TcpServer 

instanceVariableNames: 'port socket server service 
handler requests logger logProtect' 
classVariableNames: 'CanTalkToBlock 
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Instances of TcpServer provide stateless services on 
Transmission Control Protocol (TCP) Internet domain 
sockets. Each instance is uniquely associated with a port 
number on a given machine, which must be supplied 
when creating an instance. Because port must be unique, 
we use a class Portmap registry to maintain this unique¬ 
ness. Because this registry will be accessed from multiple 
threads of control, it must be protected by a mutual ex¬ 
clusion mechanism in PortmapControl. We set all this up 
when initializing the class, which also sets up the default 
security and the DefaultHandlers and DefaultServices. 

TcpServer class: 
initialize 

"Set up long-term state that is used for instance 
management." 

self beSecure. 

"If this is a re-initialize, be thread-safe." 
PortmapControl == nil ifFalse: [self shutDown], 
PortmapControl :=Semaphore forMutualExclusion. 
Portmap size >0 ifTrue: 

[Portmap copy do: [:server| server terminate]]. 
Portmap :=IdentityDictionary new. 

(DefaultHandlers :=I dentityDictionary new) at: 0 
put: self nullHandler. 

(DefaultServices := I dentityDictionary new) at: 0 
put: self discardService 

onPort: portNumber 

"Answer an active instance that provides default 
services for port <portl\lumber>." 

^Portmap 

at: portNumber aslnteger 
ifAbsent: [(self new port: portNumber aslnteger) 
resume] 

The connection security mechanism employs a block 
that answers a Boolean when passed an incoming sock- 
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et. If the block answers false, the connection is dropped 
immediately. This class method sets the default connec¬ 
tion security, but once the connection security is passed, 
an individual server can take extra precautions or imple¬ 
ment finer graduations of security. We also have utility 
methods beFriendly, which allows all connections, and 
beLonely, which only allows connections from the same 
machine, which can be useful for testing. 

TcpServer class: 
beSecure 

"Set the default security to only accept connections 
from the same network." 

CanTalkToBlock :=[:socket | 

socket getPeer networkAd dress = socket 
getName networkAddress] 

The final part of class initialization declares what to do 
when an instance is created for a port number that does 
not have a default service block or exception handler. 
Normally, an instance has its own service and handler. If 
not, a default service and/or handler is fetched from the 
class for a given port number. If even that fails, then the 
"default default" service and/or handler is used. Because 
zero is an illegal port number, we use it to hold the 
"default default" service and handler. 

TcpServer class: 
nullHandler 

"Answers handler for when nothing is to be done 
with errors. (This is generally not a wise choice!!)" 

1: exception :stream | ] 

discardService 

"Answer a 'discard' service, which is to be used 
when no service can be found for a given port." 

"^stream | ] 

Finally, accessing methods for the unique identifying in¬ 
formation for an instance must take some special actions. 

TcpServer: 

port 

"Answer the port that is listened to by this server for 
requests. If none is given, answer 7, for an echo 
server." 

"port? [7] 

port: portNumber 

"Initialize me with state needed for default 
communication on the given <portNumber>. 

Answer myself." 

self port: portNumber service: nil handler: nil 
logger: System errorLog 

The definition of the ? method was published in our 


January 1996 column. It simply answers the receiver, 
unless it isnil, in which case the argument is evaluated and 
answered. Note that we also useafew ENVY utility meth¬ 
ods in thiscode, which you will need to change if you are 
not going to usethisasan ENVY documentation server. 

With one more method, we will have all the essential 
base state needed to implement our server. This is the 
primary instance initialization method. 

TcpServer: 

port: portNumber service: serviceBlock 

handler: exceptionBlock logger: logStream 
"I nitialize me with state needed for a particular 
task. Any argument can be nil, and will be 
defaulted suitable for an 'echo' server that logs to 
the Transcript. 

<portNumber> is an I nteger port number to listen 
to. 

<serviceBlock> is a one-argument block that is 
passed a stream on a transient socket on 
<portNumber>when a connection arrives. 
<exceptionBlock> is a two-argument block that is 
passed the exception and the socket stream when 
<serviceBlock> has an unhandled exception. 
<logStream> is place to write log messages." 

requests :=WeakArray with: 0. 
service :=serviceBlock. 
handler : = exceptionBlock. 
port :=portNumber asl nteger. 
logger :=logStream ? [Transcript], 

(self class register: self) ifFalse: 

[self error: 'You already have a service on this 
port! You can only have one service 
per port per machine.'] 

Remember the need to keep track of port numbersPThis 
is handled by the class, which also needs a way to "forget' 
about port numbers as thei r server i nstances are released. 
The class also manages associations between port num¬ 
bers and the services (and their exception handlers) that 
each port provides 

TcpServer class: 

register: instance 

"Register the given <instance> of myself, unless one 
is already registered at that port. 

Answer success or failure." 

^(Portmap at: instance port ifAbsentPut: 
[PortmapControl critical: [instance]]) == instance 

unregister: instance 

"Unregister the given <nstance>of myself. Don't 
complain if I can't find it." 

PortmapControl critical: 

[Portmap removeKey: (Portmap keyAtValue: 
instance ifAbsent: []) ifAbsent: []] 
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defaultHandlerFor: portNumber 

"Answer an appropriate handler for <portNumber>, 
or a default default if none." 

^DefaultHandlers at: portNumber ifAbsent: 
[DefaultHandlers at: 0] 

defaultServiceFor: portNumber 

"Answer an appropriate service for <portNumber>, 
or a default default if none." 

^DefaultServices at: portNumber ifAbsent: 
[DefaultServices at: 0] 

Recall that class initialization set up a nullHandler and a 
discardServiceto be used when nothingelse was specified 
foragiveninstanceonagivenportnumber.Thatmeanswe 
need a way to associate other handlers and services with 
ports, so that instances can betightlycohesive with a port 
number, but loosely coupled with a service and handler. 

The "default default" of a discardService with a 
nullHandler doesn’t make for a very useful server! 

TcpServer class: 

defaultHandlerFor: portNumber is: twoArgBlock 
"Set the exception handler for <portNumber>to 
<twoArgBlock>. When evaluated, the two 
arguments will be: 

the <exception>that was the argument to the 
handle: block, 

a read-append <stream>on the transient socket 
that is being serviced. 

This is not thread safe, and should not be changed 
by some server action." 

2 = twoArgBlock numArgs 

ifFalse: [self error: 'Sorry, I need a two-argument 
clean block here!!'] 

ifTrue: [DefaultHandlers at: portNumber put: 
twoArgBlock] 

defaultServiceFor: portNumber is: oneArgBlock 
"Set the service for <portNumber>to a clean 
<oneArgBlock>. When evaluated, the argument will 
be a read-append <stream>on the transient socket 
that is being serviced." 

1 = oneArgBlock numArgs 

ifFalse: [self error: 'Sorry, I need a one-argument 
clean block here!!'] 

ifTrue: [DefaultServices at: portNumber put: 
oneArgBlock] 

MAKING A SERVER INSTANCE USEFUL 

Although you need more code for a functional server, we 
now have the base state needed to create and initialize a 
server instance. Let’s put it to work by deriving the in¬ 
stance state needed, such as the socket connection and 
input process. 


The basic service and handler are usually initialized 
from the class registry of default services and default 
handlers: 

TcpServer: 

handler 

"Answer a two-argument block that is evaluated 
upon service exception. It is passed the exception 
and a stream. Non-local returns should not be 
attempted. The block answer is discarded. 

If no handler exists, get one suitable for my port.” 

^handler ? [handler :=self class defaultHandlerFor: 
self port] 

service 

"Answer a one-argument clean block that is forked 
upon service request. It is passed a stream on the 
transient socket connection. Stream closing will be 
handled by the evaluator. The block answer is 
discarded. 

If no service has been set, initialize it to one 
appropriate for my port.” 

''service ? [service :=self class defaultServiceFor: 
self port] 

This class-instance collaboration might not seem neces¬ 
sary; in fact it isn’t. However, the temporality of server 
instances is very different from that of port-service asso¬ 
ciations, so it's useful to bind server instances tightly to a 
port number, but loosely to a service. 

For example, an instance that is providing World Wide 
Web service using HyperTextTransfer Protocol (HTTP) is 
created and discarded more frequently than the binding 
of this service to port number 80, the default HTTP port 
number. This reduces coupling in the time domain, 
which is often overlooked by designers who concentrate 
on reducing behavioral or implementation coupling. 

Now that we have a service and a handler, the impor¬ 
tant stuff can happen. An independent thread runs the 
primary server loop that waits on socket connections, 
checks to see if the connection is legal, then services the 
connection's request. 

TcpServer: 

server 

"Answer an unscheduled Process that listens for and 
dispatches service requests. 

This service loop should spend most of its time 
waiting on a socket connection, and so has a high 
priority. The service it implements is typically time- 
consuming, and so should be forked at a low 
priority, which immediately allows the server to 
resume listening for connections." 

''server ? [server :=[[ | connection | 

(CanTalkToBlock value: (connection :=self 
socket accept)) 
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ifTrue: [self serviceRequest: connection 
readAppendStream] 

ifFalse: [[connection close] fork]] repeat] 
newProcess. 

server priority: Processor userlnterruptPriority -1. 
server] 

socket 

"Answer an I OSocketAccessor that listens to my port 
for service requests." 

''socket ? 

[socket :=OSErrorHolder existingReferentSignal 
handle: [:ex | 

logger == nil ifFalse: 

[logger cr; show: 'You appear to have 
another server running on portself 
port printstring,' on this machine.']], 
ex returnWith: nil] 
do: [lOAccessor defauItForlPC 
newTCPserverAtPort: self port]] 

serviceRequest: stream 

"A connection has been accepted on a transient copy 
of my socket. <stream> is a read-write stream on that 
socket. Log the activity and provide the requested 
service in a separate thread at low priority." 

self registerRequest: ([self serviceRequestFork: 
stream] 

forkAt: Processor userBackgroundPriority +1) 

serviceRequestFork: stream 

"Provide a requested service, based on the socket 
<stream>, which at this point has not been read at 
all. If there is a problem, invoke an instance-specific 
handler. This method is forked at a low priority." 

Signal noHandlerSignal 

handle: [:ex | self handler value: ex value: stream] 
do: [self log: 'Open connection at', 

EmTimeStamp now printstring from: stream, 
self service value: stream, 
self log: 'Close connection at' EmTimeStamp now 
printstring from: stream], 

OSErrorHoldererrorSignal handle: [:ex | ] do: 

[stream close] 

Because individual requests are forked off, it is essential 
to track them down and kill them if needed, so request 
threads are registered in requests, a WeakArray. As these 
requests terminate, they are collected as garbage and 
removed from requests. 

TcpServer: 

registerRequest: serviceRequestProcess 
"A connection has been accepted and 
<serviceRequestProcess>has been forked to deal 
with it. Hang onto it weakly, so it can be killed when 
I'm killed. When it terminates, the scavenger will 
remove it from the registry." 
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(requests includes: 0) ifFalse: [requests grow "Suspend all my services so that the image can be 

replaceAll: nil with: 0]. quit and re-started." 

requests 
indexOf: 0 

replaceWith: serviceRequestProcess 
startingAt: 1 

stoppingAt: requests size 


Finally, instances need to be started, stopped, and killed. 
Ifyou are using ENVY, you'll wantto have an application 
startup method that relays to TcpServer startup to restart 
your servers, and a shutDown method that relays to 
TcpServer shutDown to suspend them. Also remember to 
have a removing method that gets rid of all instances by 
sending TcpServer initialize. 

TcpServer: 

resume 

"Begin my server." 

logger == nil ifFalse: 

[logger cr; 

nextPutAII: 'Resuming service on port'; print: 
self port; 

nextPutAII:' at'; print: EmTimeStamp now; flush], 
self server resume 

suspend 

"Suspend my server in such a way that when it 
resumes, it opens a new socket. Terminate any 
active requests in process." 

| count | 

logger == nil ifFalse: 

[logger cr; 

nextPutAII: 'Suspending service on port'; 
print: self port; 

nextPutAII:' at'; print: EmTimeStamp now. 
count :=(requests reject: [request | request = 
0]) size. 

count >0 ifTrue: [logger space; print: count; 

nextPutAII:' active requests 
cancelled.']. 

logger flush], 

requests do: [request | request =0 ifFalse: [request 
terminate]]. 

server = nil ifFalse: [server terminate, server :=nil], 
socket == nil ifFalse: [socket close, socket :=nil] 

terminate 

'Terminate my server and release my state." 

self suspend. 

self class unregister: self. 

logger == nil ifFalse: [logProtect wait, logger close], 
socket :=server :=service := handler :=logger := 
logProtect :=nil 

TcpServer class: 
shutDown 


PortmapControl critical: [Portmap do: [:server | 
server suspend]] 

startup 

"Re-start all my services." 

PortmapControl critical: [Portmap do: [:server | 
server resume]]! 

WHAT'S LEFT? 

We’ve run out of space, but this implementation sketch 
should give you enough "thoughtware" to improvise. We 
left out the thread-safe log i nterface (there are problems 
if multiple processes write to the global Transcript), and 
our implementation has more extensive logging and se¬ 
curity features and a home page facility. 

We’ll leave you with a handler and a service that im¬ 
plement a complete telnet interface to VisualWorks 
using this framework, hoping it might inspire your own 
services. 

TcpServer class: 
textualHandler 

"Answer a handler that dumps a textual stack." 

"self defaultHandlerFor: 23 is: self textualHandler" 

'i exception :stream | stream 

nextPutAII: 'Unhandled exception:'; nextPutAII: 

exception errorstring; cr; 
nextPutAII: exception initialContext printStack] 

eva I u ati on Servi ceLoop 

"Answer a service block that loops over lines of input, 
evaluating each and sending back the result." 

"self defaultServiceFor: 23 is: self 
evaluationServiceLoop" 

*j:stream | stream 

next: 6; "Discard garbage characters." 
nextPutAII: 'Smalltalk evaluation service'; cr; 
nextPutAII: Type "self close" to end session'; cr; 

nextPutAII: 'Smalltalk'. 

[stream 

print: (Compiler evaluate: stream nextLine for: 
stream); cr; 

nextPutAII: 'Smalltalk^] repeat] 

CONCLUSION 

It is easier to write client-server code in VisualWorks 
than in C, but it is still not easy enough! With some work, 
you can build a framework that reduces TCP servers to 
one or two methods 

Next issue, we’ll conclude this series by tying together 
this month’s server framework with last month’s HTML 
interface; and you'll have your Smalltalk project docu¬ 
mentation on your company’s Intranet! ffl 
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